package com.studyweb.service;

import com.studyweb.pojo.entity.User;
import com.github.pagehelper.PageInfo;

import java.util.List;

/**
 * 用户服务接口
 * 
 * <p>定义用户相关的业务逻辑操作，包括：</p>
 * <ul>
 *   <li>用户注册、登录、注销</li>
 *   <li>用户信息的增删改查</li>
 *   <li>密码管理（修改、重置）</li>
 *   <li>用户状态管理</li>
 *   <li>用户唯一性验证</li>
 * </ul>
 * 
 * @author StudyWeb Team
 * @since 1.0.0
 */
public interface UserService {

    /**
     * 用户注册
     *
     * @param user 用户注册信息，必须包含用户名、密码、手机号、邮箱
     * @return boolean 注册是否成功
     * @throws Exception 注册过程中可能出现的异常
     * @apiNote 会验证用户名、手机号、邮箱的唯一性，并对密码进行加密处理
     */
    boolean register(User user);

    /**
     * 用户登录
     *
     * @param username 登录标识（支持用户名、手机号、邮箱）
     * @param password 密码（明文）
     * @param request HTTP请求对象
     * @return User 登录成功返回用户信息（已清除密码），失败返回null
     * @throws Exception 登录过程中可能出现的异常
     * @apiNote 支持多种登录方式，会验证密码并更新最后登录时间
     */
    User login(String username, String password, jakarta.servlet.http.HttpServletRequest request);

    /**
     * 根据用户ID查询用户
     *
     * @param userId 用户ID，不能为空
     * @return User 用户信息（已清除密码），不存在返回null
     * @throws Exception 查询过程中可能出现的异常
     */
    User getUserById(Long userId);

    /**
     * 根据用户名查询用户
     *
     * @param username 用户名，不能为空
     * @return User 用户信息（已清除密码），不存在返回null
     * @throws Exception 查询过程中可能出现的异常
     */
    User getUserByUsername(String username);

    /**
     * 根据手机号查询用户
     *
     * @param phone 手机号，不能为空
     * @return User 用户信息（已清除密码），不存在返回null
     * @throws Exception 查询过程中可能出现的异常
     */
    User getUserByPhone(String phone);

    /**
     * 根据邮箱查询用户
     *
     * @param email 邮箱地址，不能为空
     * @return User 用户信息（已清除密码），不存在返回null
     * @throws Exception 查询过程中可能出现的异常
     */
    User getUserByEmail(String email);

    /**
     * 更新用户信息
     *
     * @param user 要更新的用户信息，必须包含用户ID
     * @return boolean 更新是否成功
     * @throws Exception 更新过程中可能出现的异常
     * @apiNote 不会更新密码，密码更新请使用专门的密码修改方法
     */
    boolean updateUser(User user);

    /**
     * 删除用户
     *
     * @param userId 用户ID，不能为空
     * @return boolean 删除是否成功
     * @throws Exception 删除过程中可能出现的异常
     * @apiNote 物理删除，删除后数据无法恢复
     */
    boolean deleteUser(Long userId);

    /**
     * 分页查询用户列表
     *
     * @param pageNum 页码，从1开始
     * @param pageSize 每页大小，建议10-50之间
     * @param user 查询条件，可为null表示查询所有
     * @return PageInfo<User> 分页用户列表（已清除密码信息）
     * @throws Exception 查询过程中可能出现的异常
     */
    PageInfo<User> getUserList(int pageNum, int pageSize, User user);

    /**
     * 查询所有用户
     *
     * @return List<User> 所有用户列表（已清除密码信息）
     * @throws Exception 查询过程中可能出现的异常
     * @apiNote 谨慎使用，数据量大时可能影响性能
     */
    List<User> getAllUsers();

    /**
     * 统计用户总数
     *
     * @return Long 用户总数
     * @throws Exception 查询过程中可能出现的异常
     */
    Long getUserCount();

    /**
     * 更新用户最后登录时间
     *
     * @param userId 用户ID，不能为空
     * @return boolean 更新是否成功
     * @throws Exception 更新过程中可能出现的异常
     * @apiNote 通常在用户登录成功后自动调用
     */
    boolean updateLastLoginTime(Long userId);

    /**
     * 修改密码
     *
     * @param userId 用户ID，不能为空
     * @param oldPassword 旧密码（明文），用于验证身份
     * @param newPassword 新密码（明文），将被加密存储
     * @return boolean 修改是否成功
     * @throws Exception 修改过程中可能出现的异常
     * @apiNote 会验证旧密码的正确性，新密码将使用BCrypt加密
     */
    boolean changePassword(Long userId, String oldPassword, String newPassword);

    /**
     * 重置密码
     *
     * @param userId 用户ID，不能为空
     * @param newPassword 新密码（明文），将被加密存储
     * @return boolean 重置是否成功
     * @throws Exception 重置过程中可能出现的异常
     * @apiNote 管理员功能，不需要验证旧密码，新密码将使用BCrypt加密
     */
    boolean resetPassword(Long userId, String newPassword);

    /**
     * 更新用户状态
     *
     * @param userId 用户ID，不能为空
     * @param status 用户状态（0-正常，1-禁用）
     * @return boolean 更新是否成功
     * @throws Exception 更新过程中可能出现的异常
     * @apiNote 管理员功能，用于启用或禁用用户账户
     */
    boolean updateUserStatus(Long userId, Integer status);

    /**
     * 检查用户名是否存在
     *
     * @param username 用户名，不能为空
     * @return boolean 是否存在
     * @throws Exception 查询过程中可能出现的异常
     * @apiNote 用于注册时验证用户名唯一性
     */
    boolean isUsernameExists(String username);

    /**
     * 检查手机号是否存在
     *
     * @param phone 手机号，不能为空
     * @return boolean 是否存在
     * @throws Exception 查询过程中可能出现的异常
     * @apiNote 用于注册时验证手机号唯一性
     */
    boolean isPhoneExists(String phone);

    /**
     * 检查邮箱是否存在
     *
     * @param email 邮箱地址，不能为空
     * @return boolean 是否存在
     * @throws Exception 查询过程中可能出现的异常
     * @apiNote 用于注册时验证邮箱唯一性
     */
    boolean isEmailExists(String email);

    /**
     * 通过验证码重置密码
     *
     * @param email 邮箱地址，不能为空
     * @param verificationCode 验证码，不能为空
     * @param newPassword 新密码（明文），将被加密存储
     * @return boolean 重置是否成功
     * @throws Exception 重置过程中可能出现的异常
     * @apiNote 用于忘记密码功能，需要先验证验证码的有效性
     */
    boolean resetPasswordByVerificationCode(String email, String verificationCode, String newPassword);
}